/**
 * The contents of this file are subject to the license and copyright
 * detailed in the LICENSE and NOTICE files at the root of the source
 * tree and available online at
 *
 * http://www.dspace.org/license/
 */
package org.purl.sword.client;

import org.purl.sword.base.DepositResponse;
import org.purl.sword.base.ServiceDocument;

/**
 * Interface for any SWORD client implementation.
 */
public interface SWORDClient {
    /**
     * Set the server that is to be contacted on the next access.
     *
     * @param server The name of the server, e.g. www.aber.ac.uk
     * @param port   The port number, e.g. 80.
     */
    public void setServer(String server, int port);

    /**
     * Set the user credentials that are to be used for subsequent accesses.
     *
     * @param username The username.
     * @param password The password.
     */
    public void setCredentials(String username, String password);

    /**
     * Clear the credentials settings on the client.
     */
    public void clearCredentials();

    /**
     * Set the proxy that is to be used for subsequent accesses.
     *
     * @param host The host name, e.g. cache.host.com.
     * @param port The port, e.g. 8080.
     */
    public void setProxy(String host, int port);

    /**
     * Get the status result returned from the most recent network test.
     *
     * @return The status code and message.
     */
    public Status getStatus();

    /**
     * Get a service document, specified in the URL.
     *
     * @param url The URL to connect to.
     * @return A ServiceDocument that contains the Service details that were
     * obained from the specified URL.
     * @throws SWORDClientException If there is an error accessing the
     *                              URL.
     */
    public ServiceDocument getServiceDocument(String url) throws SWORDClientException;

    /**
     * Get a service document, specified in the URL. The document is accessed on
     * behalf of the specified user.
     *
     * @param url        The URL to connect to.
     * @param onBehalfOf The username for the onBehalfOf access.
     * @return A ServiceDocument that contains the Service details that were
     * obtained from the specified URL.
     * @throws SWORDClientException If there is an error accessing the URL.
     */
    public ServiceDocument getServiceDocument(String url, String onBehalfOf) throws SWORDClientException;

    /**
     * Post a file to the specified destination URL.
     *
     * @param message The message that defines the requirements for the operation.
     * @return A DespoitResponse if the response is successful. If there was an error,
     * <code>null</code> should be returned.
     * @throws SWORDClientException If there is an error accessing the URL.
     */
    public DepositResponse postFile(PostMessage message) throws SWORDClientException;
}
